Using the level editor to view levels which you haven't yet completed may spoil your enjoyment of Monkey Shines.
WARNING - beta software
The Monkey Shines Level Editor is classed as a public beta. That is to say, there may still be some bugs hiding in there. If you find a bug, please let us know and we will do our best to fix it. Having said that, all the levels which you have received with 'Monkey Shines' were created with this editor. It has had a lot of use, and we hope we have caught all the serious problems. The editor may not behave exactly as you would expect for a Mac program. We took a few short-cuts in order to get the job done. We hope this does not inconvenience you too much. If it does, please tell us.
We strongly recommending saving your work and backing-up regularly. We hope there are no bugs which could cause your level files to become corrupted, but you never can tell. As far as we know, the editor has NEVER caused any damage to other files on disks. However, we take no responsibility should it do so. Use at your own risk.
SECOND WARNING
Creation of Monkey Shines world files from scratch is not an easy process. The level editor doesn't do the whole job. You will also need a graphics package and ResEdit. ResEdit is a development tool produced by Apple Computer. You will find it on their world wide web sites. We will also place a link to it on the Monkey Shines section of the Fantasoft web page <http://www.outreach.com/fantasoft/>
This documentation falls into two parts. First we will describe the format used for the world files so that you can create your own files. Then we will explain how to use the editor to create the levels.
1. ANATOMY OF A WORLD FILE
GRAPHICS
These are stored in PICT resources as follows:
PICT 130
PICT resource 130 stores the platforms etc. Just open a world file with ResEdit to see how these should be arranged. The first two rows of platforms block Bonzo's movement. The following three rows are platforms which Bonzo can jump up through and walk through, but still stand on. Play the game a little and you'll soon get the idea. The following six rows of tiles are used as scenery. They don't affect Bonzo in any way, but you can use them to decorate your levels.
The next two rows contains the stationary hazards - bombs, lava, light bulbs, etc. Monkey Shines supports up to 16 of these hazards. Put in whatever graphics you want (2 frames of animation) and assign the deaths to these as described later in the section 'World Resource'.
These are then followed by the stuff Bonzo can collect. There is support for animation on these, even though we decided not to use it in the end. The order of these objects must not be changed, since these are 'hard coded'.
The conveyor belts are next, followed by the dissolving platforms. The green blob to the right of these is needed for the energy bar. The items to the right are used for the interface bar at the top of the screen. These must be present.
The rest of the stuff is animations for collecting objects, exploding bombs, and numbers. It is all pretty self explanatory.
We have used certain guidelines in the creation of level files in order to give the game an overall consistent feel. Naturally we can't force you to do the same, but we strongly recommend it. We would like you to at least retain the collectable objects, animations, energy bar, numbers and some of the hazards.
PICT 200
This is the splash screen which is put up while the world is loading. The colour table for this PICT is stored in 'clut' resource 200.
PICT 1000 - whatever
These are the sprites. Each frame is 40 x 40. As you will probably have noticed by now, everything which can be drawn on screen has a 'mask' below it. This mask should be black where you want the background to show, and pure white (not nearly white - this can cause problems) where you want the sprite to be drawn. Look at our files, and you will get the idea.
Monkey Shines will allow you to use up to 47 sets of frames. If a sprite has frames for both left and right, this will count as two sets. Monkey Shines will not try to load more graphics than it has memory for. If you cannot select a particular sprite, check if you have more than Monkey Shines can load. Increasing the memory allocation to Monkey Shines(or the editor) won't help since these numbers are fixed.
PICT 5000
This is the bar for the top of the screen. You may change the icon for the world as necessary, but you may not make any other changes to this resource.
Colour Tables
These are stored in 'clut' resources. clut 200 is for the splash screen, and clut 1000 is for the game stuff. All the Monkey Shines graphics are optimised to these colour tables.
Music
The music is stored in a 'MADH' resource of ID 1000. These resources are created from MOD files (a popular music file format) by PlayerPro. PlayerPro is a shareware program written by Antione Rosset. You will find it on info-mac mirror sites and many shareware CDs. You will need to have the registered version in order to create your own MADH resources.
Patterns
These are stored in 'ppat' resources. Since ppat 1000 is used by default, your file should always have a pattern of this ID. The actual IDs of the other patterns don't matter.
World Data
There is some information about the world which is stored in a resource of type 'WrLd'. This resource will be created the first time you open the level file in the editor. You can edit the contents of this file using the editor as described below.
The Levels
Now we get down to the crux of it. The levels are stored in resources of type 'Plvl'. The starting level has ID 1000. Adding 1 moves you to the next level to the right. Adding 100 to the ID moves you to the next level down. The 'bonus stage' starts with level 10000. This should allow you plenty of scope to design worlds as big as you could possibly want.
You don't need to know anything about the internal format of the level (or world) resources, since the editor does everything you could possibly want.
2. THE EDITOR
The first thing you will see when you launch the editor is a dialog box prompting you to find a world file to edit. Find the file you want to edit and open it.
Opening world files can take a little while on slower macs. Please be patient.
The Toolbar
Once the file is open, you will see a range of icons along the top of the window. These are (pretty crude) pop-up menus which allow you to select the tiles which you want to place. There is also an eraser tool to delete tiles. Click on a few of the icons to see what they are.
Menus
The file menu has all the things you would expect. The 'New File' option is dimmed, since this feature is not implemented. The only way to create a new world file at the moment is with a resource editor such as ResEdit.
The 'Level' menu allows you to open levels, create new levels, save them or delete them. You can also undo your changes by reverting to the saved version of the open level.
The 'Open Level', 'New Level' and 'Delete Level' options bring up the level selection dialog. You can either type the number of the level you want into the editable text item, or click on the buttons to navigate the world file and put your levels together how you want. This dialog has a preview button to help you find the level you want.
'Object' menu has only one item - assign ID. See 'Object Numbering' below for an explanation.
The 'sprites' menu allows you to place, move and delete Bonzo's natural enemies. This is discussed in detail in the section 'Monsters, etc.'. The first item 'sprites visible' doesn't do anything - it was an idea which we never got round to. Sorry!
The 'Misc' menu allows you to edit a number of things:-
Place Bonzo - if Bonzo comes onto a screen, and dies without landing safely, he will be placed on the previous screen. Use this menu to define where he will be placed. Select the menu, then click on the screen where you would like to place Bonzo. Important, this MUST be done for ALL levels - failing to do so may cause the game to crash.
World Info - see 'World resource' below.
Select Pattern - self explanantory - this item allows you to choose the background pattern used by the level.
Autonumber items - see 'Object Numbering' below.
Object Numbering
In order for the game to keep track of which objects Bonzo has collected, each one has a unique ID number. You can set these with the 'assign ID' item in the 'Object' menu - select this menu item, then click on the object you would like to assign a number to. A dialog will then appear which allows you to set the ID. Valid numbers are in the range 0 - 511.
Alternatively you can autonumber the objects for the whole world by selecting 'Autonumber items' from the 'Misc' menu.
World Resource
World Info - here you can manually set the number of keys and fruit. If you autonumber items, you should never need to edit the numbers here. You also need to tell the game which levels to find the exits on. You should enter the number of the level which contains each type of door in the appropriate text boxes. See the following section for an explanation of the rest of this dialog.
Characteristics of stationary hazards
Each hazard (bomb, light bulb, lava, etc.) has its own characteristics. These are
- which sounds does it cause. The sounds are stored in 'snd ' resources in the Monkey Shines application. Subtract 128 from the resource ID to obtain the number to use here.
- if it explodes - hazards may explode (check the check box). If so, they can play a sound as above.
Monsters etc.
When you select 'Edit Sprite' or 'New Sprite' you will get the editing dialog. This is really 2 dialogs in 1, which you can move between using the 'next' and 'prev' buttons.
The first dialog allows you to define a rectangle within which the sprite moves. The valid ranges are
top - 80 to 440
bottom - 120 to 480
left - 0 to 600
right - 40 to 640
The speed values define how fast the sprite moves in each direction. The starting position, funnily enough, defines where the sprite starts. This doesn't have to be within the rectangle, and you will be able to get some pretty unusual movement patterns by playing with these values.
The second dialog allows you to change how the sprite looks (use the 'next' and 'prev' buttons at the top right of this dialog) and how it is animated. The best way to discover what these do is to play with the settings.
What you will notice is that each sprite can be defined as a door or energy drainer. If you define a sprite as a door, and mark the current level as the level for the 'Exit door' in the world info, this sprite will not appear until you have all the red keys, and then it will function as if it were a door. It doesn't have to look like a door, but unless you want to confuse people horribly, we recommend that you stick with the correct graphics. Draining energy is not restricted to the bee, but we recommend that you don't use it for other sprites since players will spend their time avoiding the sprite and get bored or frustrated.
And yes, the door can move if you really want it to.
There is just one more important point about sprite animation. If a sprite moves too fast, it will leave a trail behind. This is not a bug, but is another consequence of the optimisations we made in the graphics code.
Suppose you have a 40 x 40 sprite which you want to move to the right 2 pixels each frame (i.e. speed 2). The 2 leftmost columns in the sprite animation frame must be blank in order for the sprite not to leave a trail. We don't feel that this is a major limitation.
Important Limitations
1. You may not have more than 25 collectable items per screen.
2. You may not have more than 10 monsters (these also include doors) per screen.
Writing a good game is about taking the shortcuts which don't matter so that you can get good performance. In our case we chose a less general method of drawing the sprites since it was much faster and allows Monkey Shines to run on slower Macs (LC, LCII, LCIII and their Performa equivalents). If we hadn't done this, Monkey Shines wouldn't work on those machines - we consider that a fair compromise.
The result of all this is that if two sprites overlap, there will be a point where on sprite partially erases the other.
The way to avoid this is to make sure that sprites are placed so that they cannot possibly overlap. The same applies to sprites overlapping with conveyor belts, dissolving platforms, points (yum), hazards and explosions. In fact, the only things which are not affected by this are the 'normal' platforms, scenery, and Bonzo. With a bit of imagination, this won't become a problem.
At this time we are considering an upgrade to Monkey Shines which will remove this limitation. An overhaul of the sprite engine would push it out of the range of capability of 68020 and 68030-based Macs. If and when we do this, we will still support the 'original' Monkey Shines, so that there is always a bug-free version which will work on these slower Macs, and there will be for the forseeable future.
Known Problems
When selecting 'new level', the okay button will be initially enabled, even if there is already a level with that resource ID. You still won't allow you to overwrite the level though. This will be fixed as soon as we can work out why it is happening.
The Future
We will be working on the editor in order to get it into better shape. We would welcome your comments.
At some point, there will probably be a Fantasoft CD which will contain all our software. There will be plenty of space on it for 3rd party Monkey Shines levels, so get designing. If you want to set up an unofficial Monkey Shines web site, tell us about it - we may be able to provide you with suitable artwork.
The Last Word
If there is ever a Monkey Shines 2, it will use a bigger more flexible sprite engine. We have learned from writing Monkey Shines, and we have lots of ideas (although we could always use more). It may sound like a cliche, but the best way to convince us to produce a Monkey Shines 2 is to register Monkey Shines. We will be far more inclined to work on a sequel if we are making a little money. Sorry if that sentiment offends you, but we have day jobs which take a lot of our time. Monkey Shines has taken a huge amount of time and effort to produce.
How to contact us
By mail:
Fantasoft, LLC
P.O. Box 14261
Madison
WI 53714-0261
U.S.A.
By phone/fax: (608) 222 8468
By email: fantasoft1@aol.com
Visit our world wide web pages: <http://www.outreach.com/fantasoft>
